-----------------------------------------------------------------------------------------------
--
-- CLEAN_Address PL/SQL Batch and AJAX Verification
--
-- History:
--   12/13/08 - Created
--
-- Copyright (c) 2000-2008 Runner Technologies, Inc.  All Rights Reserved.
-- www.RunnerTechnologies.com   sales@RunnerTechnologies.com   877-784-0003  561-395-9322
-----------------------------------------------------------------------------------------------


-----------------------------------------------------
Directories:
-----------------------------------------------------

The following directories contain PL/SQL Packages, reports, and AJAX sample code meant to be
customized for your specific application)

pkg          - CLEAN_Address application specific packages
reports      - Pre-generated reports after a batch update
AJAX_Example - Sample AJAX Code illustrating how to call CLEAN_Address from a static HTML page


-----------------------------------------------------
Setup
-----------------------------------------------------

0) Preface

   NOTE: We recommend renaming the packages to something custom to your specific application by
         renaming the APP abbreviation to your application name, ie "CLEAN_Address_XYZ".

   NOTE: We recommend loading these packages in your application schema instead of the CLNADDR schema
         for security purposes.  This does require granting access from some objects in the CLNADDR
         schema to your application schema.

   Packages:
   -------------------------------------------------------------------------------------------
   CLEAN_Address_APP      - Application base package for verifying a single address
                            as well as a sample batch verification procedure
   CLEAN_Address_APP_AJAX - AJAX support package for accepting real-time requests
   CLEAN_Address_APP_UE   - User Exit extensions package for customizing standards.  The user exit
                            package contains pre- and post- events that can be used to customize the
                            address verification functionality.

1) Load the support packages into your application schema or the CLNADDR schema.

   To load the packages, run the following scripts in the "pkg" directory in the appropriate schema:

   NOTE: The next script creates a table containing additional address fields.  An alternate choice
         is to add theses additional columns to your application address table directly to avoid
         the join to this table in reports.

  APP:SQL> @pkg/crt_cln_address_APP.sql

   NOTE: Because of dependencies, you may see some package compilation errors initially, but after
         all packages have been loaded, they should compile cleanly.

  APP:SQL> @pkg/loadpkg.sql
  APP:SQL> @pkg/loadpkg_user_exit.sql
  APP:SQL> @pkg/loadpkg_ajax.sql

-----------------------------------------------------
Steps for performing a PL/SQL Batch verification:
-----------------------------------------------------

There are many different ways to do a batch verification.

You can either load your address data into the CLN_ADDRESSES table or copy and modify the
supplied procedure on the CLEAN_Address_APP package, named Batch_Verify_CLN_ADDRESS according
to your specific address table layout.

To load the data into the supplied CLN_ADDRESSES table:

  Files Used:
  cln_addresses_sample.dat          - CSV address data file
  cln_addresses_sample.ctl          - SQL*Loader Control File
  load_clnaddr.cmd                  - DOS script to load data with control file
  load_clnaddr.sh                   - UNIX script to load data with control file

1) Save your data in CSV format in the cln_addresses_sample.dat file.
   NOTE: Field layout must match that of the control file: cln_addresses_sample.ctl

2) Load the Data.  Run the following to load the data into CLN_ADDRESSES:

  DOS> load_clnaddr cln_addresses_sample clnaddr@SID

  UNIX$ ./load_clnaddr.sh cln_addresses_sample clnaddr@SID

3) Verify the addresses.  Sign into SQL*Plus as clnaddr and run the following:

  clnaddr:SQL> @scripts/batch_verify_CLN_ADDRESSES.sql

4) Reporting.  Run the summary and detail reports to see the results.
   NOTE: These are best run from a GUI tool like PL/SQL Developer or Toad

   SQL: address_error_detail.sql   -- Address Verification Summary SQL Report
   SQL: address_error_summary.sql  -- Address Verification Detail SQL Report

-----------------------------------------------------
Steps for performing a Real-Time AJAX Address verification:
-----------------------------------------------------

1) Edit your application HTML page where an address is entered.

2) Add the text in the "AJAX_example/ajax_javascript_calling example.txt" after the address entry HTML code.

3) Customize the code at the bottom of the sample to reference your specific Address
   field names and layout. Pay close attention to the Url line which calls the Oracle DAD.

   NOTE: If you are not using the Oracle Application Server with mod_plsql extensions you may need to
         create your own "wrapper" page which makes the call to the CLEAN_Address_AJAX procedure.

   NOTE: If you ARE using the Oracle Application Server, create a database access descriptor (DAD) in which
         the AJAX code can call.

-----------------------------------------------------------------------------------------------
Reports / Scripts:
-----------------------------------------------------------------------------------------------
* test_cln_APP
   - Shows the integration code for verifying addresses real-time.
   - Also great for testing individual addresses.

* batch_verify_CLN_ADDRESSES
   - Shows how to call the batch verification procedure for the respective table with all
     available parameters